/*
 * Copyright (c) 2008, Roman Bosak
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *  - Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *  - Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *  - Neither the name of the DailyDevelopment nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
 * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
 * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
 * THE POSSIBILITY OF SUCH DAMAGE.
 */
package com.dailydev.jira.portal.config;

import java.util.Set;

/**
 * Interface providing methods to manage and access configuration of portal page
 * sharing.
 * 
 * @author Roman Bosak, roman.bosak@gmail.com
 */
public interface IPortalPageSharingConfiguration {

    /**
     * Returns {@link Set} of all {@link ISharedPortalPage} instances
     * representing configurations of shared portal pages.
     * 
     * @return {@link Set} of all {@link ISharedPortalPage} instances
     *         representing configurations of shared portal pages
     */
    Set < ISharedPortalPage > getSharedPortalPages();

    /**
     * Removes sharing configuration of portal page specified by
     * <code>portalPageId</code>.
     * 
     * @param portalPageId
     *            ID of portal page which sharing configuration should be
     *            removed
     * @return already removed sharing configuration of portal page
     * @throws PortalPageSharingConfigurationException
     *             thrown if there are some problems with configuration updates
     */
    ISharedPortalPage removeSharedPortalPage(Long portalPageId)
            throws PortalPageSharingConfigurationException;

    /**
     * Adds or updates sharing configuration of portal page.
     * 
     * @param sharedPortalPage
     *            sharing configuration that should be added
     * @return already added sharing configuration
     * @throws PortalPageSharingConfigurationException
     *             thrown if there are some problems with configuration updates
     */
    ISharedPortalPage addSharedPortalPage(ISharedPortalPage sharedPortalPage)
            throws PortalPageSharingConfigurationException;

    /**
     * Returns true if there is a sharing configuration for portal page with
     * <code>portalPageId</code>.
     * 
     * @param portalPageId
     *            ID of the portal page to check if it is shared
     * @return true if there is a sharing configuration for portal page with
     *         <code>portalPageId</code>. Otherwise return false.
     */
    boolean isShared(Long portalPageId);

    /**
     * Returns sharing configuration for portal page specified by
     * <code>portalPageId</code> or <code>null</code> if no sharing
     * configuration for the page exist.
     * 
     * @param portalPageId
     *            Id of the portal page for which we want to retrieve sharing
     *            configuration
     * @return sharing configuration for portal page specified by
     *         <code>portalPageId</code> or <code>null</code> if no sharing
     *         configuration for the page exist
     */
    ISharedPortalPage getSharedPortalPage(Long portalPageId);
}
